Getting Started
Creating a New Extension
You can scaffold a mobile feature or widget in two ways:
| Approach | Command | Best for |
|---|---|---|
| Offline starter | nx generate @cdx-extensions/widget-template-mobile:feature|widget | Blank React Native library with no catalog |
| Catalog templates | nx run generate-mobile-extensions | DI-backed starters from the extension template catalog |
Both create a correctly structured React Native library wired for @cdx-extensions/di-sdk (PlatformSDK), built with tsup, and aligned with the CDX mobile patterns used in the reference implementations.
For catalog-driven generation (type picker, category picker, npm template overlays), see Extension Template Catalog. Quick reference:
nx run generate-mobile-extensions # interactive: type → category → template → fiId → name
nx run generate-mobile-widget # interactive: widget only
nx run generate-mobile-feature # interactive: feature only
nx run generate-mobile-widget -- --template=investment-portfolio --fiId=0123 --name=acme-portfolio
The Offline Starter Template
Use the offline starter when you want a blank scaffold without the catalog. The package @cdx-extensions/widget-template-mobile exposes two generators — feature and widget.
Prerequisites
Before you run either generator, complete the prerequisites and environment setup described in the CDX Extensibility Apps README.
Choose a Generator
| Generator | Use when | Example |
|---|---|---|
feature | You are building a full-screen experience the host mobile banking app maps to a dedicated bottom tab, or surfaces in the More menu. |  Sample Feature — bottom tab with a full-screen experience |
widget | You are building a component the host mobile banking app embeds in the existing home screen. |  Sample Widget — embedded component on the home screen |
Commands
Feature — new bottom tab with a full-screen experience:
nx generate @cdx-extensions/widget-template-mobile:feature --fiId=<fi-id> --name=<name>
Widget — embedded component:
nx generate @cdx-extensions/widget-template-mobile:widget --fiId=<fi-id> --name=<name>
| Option | Required | Description |
|---|---|---|
--fiId | Yes | Your FI Id. Used as the package scope — the generated package name is @<fiId>-extensions/<name> |
--name | Yes | Name of the feature or widget (e.g. account-summary). Used as the Nx project name and folder name |
Examples
# Feature
nx generate @cdx-extensions/widget-template-mobile:feature --fiId=0000 --name=my-feature
# Widget
nx generate @cdx-extensions/widget-template-mobile:widget --fiId=0000 --name=my-widget
What Gets Created
Feature (scaffolded under features/mobile/<name>/ by default):
features/mobile/my-feature/
├── src/
│ ├── my-feature.tsx ← feature component — start here
│ ├── index.ts ← named + default exports
│ ├── config.ts ← API base URL (baseUrl) and endpoint path (apiPath)
│ └── types/
│ └── branding.ts ← MobileBrandingTheme types and resolveColors helper
├── package.json
├── project.json
├── tsconfig.json
└── README.md
Widget (scaffolded under widgets/mobile/<name>/ by default):
widgets/mobile/my-widget/
├── src/
│ ├── my-widget.tsx ← widget component — start here
│ ├── index.ts ← named + default exports
│ └── types/
│ └── branding.ts ← MobileBrandingTheme types and resolveColors helper
├── package.json
├── project.json
├── tsconfig.json
└── README.md
The widget starter template is minimal. Add API calls, navigation, or any SDK capability as your project requires — see the investment-portfolio reference implementation for an example that uses getHttpClient().
After You Generate
The generator registers your project in the sandbox automatically. From the repository root:
npm install
npx nx start mobile-sandbox
Press i for the iOS Simulator, a for Android Emulator, or scan the QR code with Expo Go on a physical device. The sandbox provides the mock platform (user context, branding, HTTP client) so your feature or widget can run without the production host app.
For how widgets appear inside the banking-style home layout (scroll, chrome, and tabs), see Mobile Playground for more.
What You Can Edit
| File / Folder | Can you edit? | Notes |
|---|---|---|
src/ | Yes, freely | All your UI and business logic goes here |
package.json | Partially | Change name, version, peerDependencies. Keep the build scripts and tsup config as-is |
project.json | Partially | Only change name, outputs, and cwd to match your project folder |
tsconfig*.json | No | Required TypeScript config |
Common Mistakes to Avoid
| Mistake | Why It Breaks |
|---|---|
Using fetch() or Axios directly instead of sdk.getHttpClient() | Bypasses platform auth and security in production |
Importing from @cdx-extensions/di-sdk-mobile in feature or widget code | Only the host app initialises the platform — features and widgets import from @cdx-extensions/di-sdk only |
| Adding peer or runtime dependencies outside the versions listed in the CDX Extensibility Apps README | Version conflicts with the host mobile banking app at runtime |
Forgetting to export from src/index.ts | The sandbox (or host app) cannot import your component |
Changing the tsup build scripts in package.json | Breaks the CJS/ESM dual output required for Metro and production bundling |
Next Steps
Mobile platform guides:
- SDK Reference — SDK packages, methods, and usage
- Extension Template Catalog — Scaffold from DI template catalog
- Mobile Playground — Realistic home screen for previewing embedded widgets
- Platform Capabilities (Local) — How local development works with mock data
- Host App Integration — Repository structure and submission process